CodeAgent CLI 项目深挖按单期模块组织。需求与总览：需求分析 / 整体设计方案；核心模块：ReAct和tool call / plan和DAG / Memory系统 / Multi-Agent / RAG代码检索 / 人工审批 / 多并发 / 联网搜索 / 接入MCP / DevTools MCP / CDP会话复用 / web-access Skill；产品化：TUI三形态 / Git快照回滚 / Prompt分层与模型接入 / 异步任务与RuntimeAPI / 微信iLink通道。

介绍这个项目（面试口述稿）

30 秒版

我做一个叫 CodeAgent CLI 的 Java 版 coding Agent，对标 Claude Code：在终端里给模型一个目标，它自主规划、调用工具、读写代码库、执行命令，直到任务完成。技术上是自研的 ReAct 循环，基于 Spring AI 做模型层抽象，支持 ReAct / Plan-and-Execute / Multi-Agent 三种执行模式、16 个内置工具加 MCP 动态扩展，配了路径围栏、命令黑名单、人工审批、审计日志四层安全防线。我按 23 期迭代把它从最小可用做到产品化，期间重点解决了上下文压缩、并行工具执行的确定性、Agent 自主性与可控性的平衡这三个问题。

2 分钟版

背景与动机：我常用 Claude Code 这类产品，但遇到 Agent 选错工具、丢上下文时只能换个说法碰运气——不知道问题出在 Prompt、工具描述、上下文管理还是模型能力。所以我从零实现一个 coding Agent，把关键模块完整走一遍，拿到源码级的理解。

架构：五层——交互层（inline TUI 三形态）、编排层（三种执行模式）、能力层（ToolRegistry、Memory、快照）、接入层（五家模型的 OpenAI 兼容瘦实现、MCP）、渠道层（终端 / Runtime API / 微信）。架构铁律：三条执行路径共享同一套工具、记忆和快照能力，不为某个模式造孤立功能。

三种执行模式，本质是「决策权在哪」的递进：ReAct 把决策权交给模型逐轮自决，配三重兜底（工具名+参数签名停滞检测、硬轮数、token 预算）；Plan-and-Execute 先由 Planner 生成 DAG、用户确认后再执行，任务失败且进度过半前触发重规划；Multi-Agent 加了独立 Reviewer 的质量关——审查解析失败保守判不通过，重试上限 2 次。

两个代表性问题：一是上下文压缩——第一版压缩压不到真正发给 LLM 的消息列表（压的是内部记忆），预算看着降了请求没变小，这是踩坑后补的双轨压缩，切割点强制落在 user 消息边界保护 tool_call/tool_result 配对；二是并行工具执行——多工具并行提速，但回灌必须按原始 tool_call 顺序，用 invokeAll 的保序契约解决「乱序完成、按序收集」。

安全设计：明确拒绝「沙箱」叙事，做的是 HITL 人工审批 + PathGuard 路径围栏 + CommandGuard 黑名单快失败 + 按天 JSONL 审计四层防线——人管「要不要做」，策略管「能不能做」，用户批准也越不过策略硬规则。

收尾：这个项目让我对 Agent 系统的诊断能力有了质变——出错时能区分是检索召回不足、压缩损失、工具描述不清还是模型决策偏差；也让我在用 Claude Code 时知道怎么给任务边界和验收条件。

追问衔接

追问	去处
ReAct 具体怎么做的 / 防死循环	ReAct和tool call
Plan 和 DAG 细节 / 重规划	plan和DAG
Multi-Agent 编排 / Sub-agent	Multi-Agent
记忆怎么设计 / 压缩踩坑	Memory系统
工具审批 / 并行执行	人工审批 / 多并发
MCP / 浏览器自动化	接入MCP / DevTools MCP / CDP会话复用
Skill 系统	web-access Skill
和 LangChain 比怎么选	上方「选择 LangChain/LlamaIndex 还是自研」

项目背景与定位

CodeAgent CLI 是一个面向商业使用的 Java Agent CLI 产品，对标 Claude Code：在终端里给模型一个目标，由 Agent 自主规划、调用工具、读写代码库、执行命令，直到任务完成。项目从第一期的 ReAct 单代理循环开始，按期迭代到第 23 期（微信 iLink 通道），每一期都是一个可交付的能力增量——这个演进过程本身就是「Agent 产品如何长出来」的完整样本。

目标用户与场景

• 开发者（主用户）：在真实代码库里完成定位、修改、重构、跑测试等任务，要求精确读写与安全边界；
• 长任务用户：多步骤、有依赖关系的复杂任务，需要计划先行、确认后执行；
• 非终端渠道用户：通过微信等通道远程使用 Agent（非交互环境，安全策略必须更严格）。

能力需求清单

1. 三种执行模式：ReAct 单代理循环（默认）、Plan-and-Execute（计划生成 + 用户确认 + DAG 依赖执行）、Multi-Agent（planner/worker/reviewer 编排）；
2. 工具系统：文件读写、glob/grep 精确检索、执行命令、RAG 语义代码检索、联网搜索/抓取、MCP 动态工具、Skills 技能包、save_memory；
3. 记忆与上下文工程：短期对话 + 长期事实记忆、CODEAGENT.md 分层注入、接近窗口预算时自动压缩；
4. 安全边界：路径围栏、命令黑名单快失败、危险操作人工审批（HITL）、按天 JSONL 审计；
5. 产品化：inline TUI、LSP 诊断注入、Git 快照与回滚、异步后台任务 + Runtime API、图片输入、微信通道。

关键技术矛盾（面试主线）

1. 自主 vs 可控：退出权交给 LLM 自决（循环以「无 tool_calls」为主退出条件），但用 AgentBudget 做三重兜底——停滞检测（工具名+参数签名连续 3 次相同）、硬轮数、token 预算（默认放开，显式开启）；
2. 能力共享 vs 模式隔离：三条执行路径共享 ToolRegistry / MemoryManager / SnapshotService，禁止为某个模式造孤立能力（CODEAGENT.md 明文约束）；
3. 上下文有限 vs 任务连续：压缩必须在 user message 边界切割，否则切断 tool_call/tool_result 配对——项目文档坦承第一版压缩「压不到真正发给 LLM 的消息」，双轨压缩是踩坑后的补丁（见 Memory系统）；
4. 开放工具 vs 安全：明确拒绝「沙箱」叙事，主张 HITL + PathGuard + 黑名单 fast-fail + AuditLog 四层辅助，黑名单自认反模式——权衡表述诚实。

在构建 Agent 框架时，选择 LangChain/LlamaIndex 还是自研？

“CodeAgent CLI 的核心 Agent 循环是自研的，基于 Spring AI 做模型层抽象。“

“先说 LangChain 的优势。生态是真的强，500 多个集成，向量数据库、模型提供商、工具连接器几乎全覆盖。做 POC 验证想法，差不多两三天就能出一个能跑通的 Demo。社区活跃，遇到问题基本都能搜到解法。”

“但它的问题也是真实存在的。”

“第一，调试成本高。一个简单的工具调用，经过好几层框架内部的包装，报错时堆栈太多。你想知道‘为什么这次工具调用返回了空’，得先理解框架的内部状态。”

“第二，版本是历史包袱。LangChain 早期从 0.1 到 0.2 到 0.3 几乎是三个不同的框架，API 断裂式变更。虽然到了 1.x 稳定了不少，但这段历史说明一件事——你的生产代码依赖别人的迭代节奏，这本身就是风险。”

“第三，抽象。框架的设计是通用的，但你的业务是完全不同的。为了适配，你得写大量代码把自己的逻辑塞进框架的接口里。”

“自研的优势是完全掌控每一步。调试直接看自己的代码，性能瓶颈知道在哪，迭代节奏自己定。况且现在 Agent 的 Coding 能力已经很强了，完全不用担心自研。”

“我的判断——做技术验证和快速原型，用框架。做生产系统，核心自己写，框架当工具库用。”

你做的 coding agent 和 Claude Code 与 Codex 区别在哪？

Claude Code 和 Codex 是面向生产效率的成熟产品，而 CodeAgent CLI 是我为了掌握 Agent 底层机制而实现的、强调可观测和可定制的工程化 Coding Agent。

我做这个项目，是因为在使用成熟 Coding Agent 时产生了一个疑问：它到底是怎么理解指令、选择文件和工具，以及管理多轮上下文的？

如果只会使用而不了解原理，当 Agent 选错工具、丢失上下文或者生成的代码不符合项目风格时，我通常只能换一种说法重新尝试，很难定位到底是 Prompt、工具描述、上下文管理还是模型能力出了问题。

因此我从零实现了 CodeAgent CLI，把 ReAct、Tool Calling、Memory、MCP 和安全审批这些关键模块完整走了一遍。完成之后，我对 Agent 系统有了源码级理解：我能分析一次错误是检索召回不足、上下文压缩损失、工具 Schema 描述不清，还是模型本身的决策偏差，而不仅仅是重新提问碰运气。

这种理解也反过来提升了我使用 Claude Code 和 Codex 的能力。例如我知道怎样提供任务边界和验收条件，什么时候应该压缩或重建上下文，以及怎样设计 Tool 的名称、描述和参数结构来提高调用准确率。